\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Basic User Interface Functions}

\beginChapter 2.{Common Lisp Object System Specification}%
{Basic User Interface Functions}{Basic User Interface Functions}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}
This chapter describes the functions provided by
the \CLOS\ Basic User Interface.
\vfill
\endSection%{Introduction}


\begincom{add-method}

\label Purpose:

The function {\bf add-method} adds a method to a generic function.  It returns
the modified generic function as its result.

\label Syntax:

\Defun {add-method} {generic-function qualifiers specializers function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of argument specializers of
the type that may be given to {\bf defmethod}.

The {\it function\/} argument is the method function.

\label Values:

The modified generic function is returned as the result of {\bf add-method}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod

make-generic-function}

\endcom


\begincom{argument-precedence-order}

\label Purpose:

The function {\bf argument-precedence-order} returns two values: a
list of the required parameters of the generic function, in the order in which
they were specified, and a list of these same parameters, in order of
decreasing precedence.

\label Syntax:

\Defun {argument-precedence-order} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

\label Values:

Two values are returned: a list of the required parameters of the generic
function and a list of the same parameters, in order of decreasing
precedence.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{call-next-method}

\label Purpose:

{\bf call-next-method} is used within the body of a method.  It calls
the "next method" with the same arguments that this method received.

For the precise definition of "next method" see the section "Method
Selection and Combination".  {\bf call-next-method} returns the value or
values returned by the method it calls.  Further computation after {\bf
call-next-method} returns is possible, so this provides a general
imperative form of method combination.   

The type of method combination in use determines which kinds of methods 
allow {\bf call-next-method} to be used.  The default method combination
type, {\bf :daemon}, allows {\bf call-next-method} to be used inside
primary methods and {\bf :around} methods.  If you define a new type of
method combination using the short form of {\bf define-method-combination}, 
{\bf call-next-method} can be done in {\bf :around} methods only.

\label Syntax:

\Defun {call-next-method} {}

\label Arguments:

{\bf call-next-method} is called with no arguments.

\label Values:

{\bf call-next-method} returns the value or values returned by the
method it calls. 
 
\label Remarks:

If {\bf call-next-method} runs out of methods, it signals an error. 

Neither argument defaulting, nor the use of {\bf setq} or {\bf let} on 
variables with the same names as parameters affects {\bf call-next-method}.

Possible extensions:

{\bf call-next-method} {\it arguments\/}  When at least one argument is
given, {\bf call-next-method} supplies those
arguments instead of the arguments that this method received.  

{\bf apply-next-method} {\it arguments\/} This is like {\bf
call-next-method} except that it uses {\bf apply} instead of {\bf
funcall}.  That is, the last argument is really a list of arguments.

\label See Also:

See the sections ``Method Selection'' and ``Method Combination.''

\endcom



\begincom{change-class}

\label Purpose:

The function {\bf change-class} changes the class of an instance to the
new class.  It destructively modifies and returns the instance.

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument must be an instance whose metaclass is
{\bf class}.  % (a standard object)

The {\it new-class\/} argument is a class object.

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[The internal protocol of {\bf change-class} needs to be spec'd.]

\endcom



\begincom{class-of}

\label Purpose:

The function {\bf class-of} returns the most specific class of which the 
given object is an instance.   Every Common Lisp object has a class.  

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:


\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with {\bf make-instance} and its class was
not changed, the class that is
returned is the class that was specified as the {\it class\/} argument 
of {\bf make-instance}.

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
standard-type-class} or a subclass of {\bf standard-type-class} (other
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

Note that {\bf class-of} can never return an abstract class.

\endcom



\begincom{defclass}

\label Purpose:

The macro {\bf defclass} defines a new class, which is a 
new data type with named slots.  It returns the class-object as 
its result.

{\bf defclass} syntax offers options that allow for providing default
initialization of the slots, and for requesting that functions be 
automatically generated to read and write the values of the slots, or to
construct new instances.   By default, no accessor, reader, constructor,
or predicate function is defined.   Also, slots are not by default
initable. 

When you define a class you are also defining a type.  That is, 
({\bf typep} {\it object class-name\/})  
is true if the object is an instance of the given class.

\label Syntax:

[Note:   can you put the following Syntax description into the box format?]

(defclass class-name ({super-class-name}*) ({slot-spec}*) {class-option}*)

class-name ::= a non-null symbol

super-class-name ::= a non-null symbol

slot-spec ::=  slot-name | 
               (slot-name default-value) |
               (slot-name {slot-option}*) 

slot-option ::= :accessor generic-function-name |
		:allocation allocation-type |
                :default-value form |
		:initable symbol |
		:reader generic-function-name 
		
allocation-type ::= :instance | :class | :none | :dynamic 

class-option ::= (:accessor-prefix string-or-symbol) |
		 (:constructor symbol [boa-arglist]) |
                 (:documentation string) |
		 :initable-slots |
		 (:instantiable t-or-nil) 
		 (:metaclass class-name) |
		 (:predicate symbol) 
		 (:reader-prefix string-or-symbol) 

boa-arglist ::= as you have it below 

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name includes} \paren{\star{\curly{slot-description}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it includes\/}::$=$ (\star{\curly{class-name}})\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-description\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \brac{initform \star{\curly{slot-option}}})\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :initialize-only} {\it flag\/} $\vert$\cr
\+&&{\tt :accessor} {\it generic-function-name\/} $\vert$ {\tt :accessor nil} $\vert$ \cr
\+&&{\tt :read-accessor} {\it generic-function-name\/} $\vert$ {\tt :read-accessor nil} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessors-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :readers-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&{\tt :constructor} $\vert$ ({\tt :constructor} {\it symbol\/}) $\vert$ ({\tt :constructor nil}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol boa-arglist\/}) $\vert$\cr
\+&&{\tt :predicate} $\vert$ ({\tt :predicate} {\it symbol\/}) $\vert$ ({\tt :predicate nil}) $\vert$\cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\+&&({\tt :instantiable t}) $\vert$ ({\tt :instantiable nil}) \cr
\+&&({\tt :documentation} {\it string\/})\cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform} {\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject

\label Arguments:

{\it class-name\/} is a non-null symbol that names the class being
defined.  If a class is already defined with this name, this definition
replaces the old definition.

Each {\it super-class-name\/} is a non-null symbol naming a class to be
included as an integral part of this class.  The class now being defined
will inherit characteristics (such as slots) and behavior (such as 
methods) from each of its super-classes (and from their super-classes).
Each {\it super-class-name\/} must refer to a user-defined class, not a 
built-in class.   

Each {\it slot-spec\/} includes the name of the slot, which is a
non-null symbol.   The {\it slot-name\/} can be given alone, or in a list.   

{\it slot-spec\/} can be a list of the slot name and its {\it
default-value\/}, which can be any form.  When an instance is made and
no initial value for this slot is provided as an argument to {\bf
make-instance}, the slot is initialized to the value of this form.  The
{\it default-value\/} is evaluated every time it is used. 

{\it slot-spec\/} can also be a list of the {\it slot-name\/} followed
by one or more {\it slot-options\/}, each of which 
specifies an option that is specific to this slot.  

The defined {\it slot-options\/} are:

{\bf :accessor} {\it generic-function-name\/} This specifies that a
method for an accessor function should automatically be generated for
this slot.  An accessor is used to read the value of this slot, and
{\bf setf} may be used with it to write the value of the slot.  {\it
generic-function-name\/} must be a non-null symbol.

{\bf :allocation} {\it allocation-type} This specifies where storage is
allocated for this slot.  The {\it allocation-type\/} can be one of 
these keywords: {\bf :instance}, {\bf :class}, {\bf :dynamic}, {\bf
:none}.  The semantics of these keywords are:

{\bf :allocation :instance} Storage is allocated in the instance itself;
each instance has its separate value for this slot.  This is the
default.

{\bf :allocation :class} Storage is allocated in the class.  Thus a
single value for this slot is shared by all instances.  Class slots
(like other slots) are inherited by subclasses of this class.  The state
associated with a class slot is stored only where it is explicitly
specified in the class.  If a local description of a slot is provided,
it completely overrides an inherited description of a component class. 

{\bf :allocation :dynamic} This option is still under discussion; it is
not yet clear whether it should be in the standard.  The purpose of this
option is to specify:  Storage is allocated in the instance at the time
of the first use of the slot.  If the slot is initialized with a keyword
argument to {\bf make-instance}, the slot is allocated then.  If the
first access is a read, then storage is allocated and the default value
declared in the {\bf defclass}, if any, is stored in the slot and
returned.  If the first access is a {\bf setf}, then storage is
allocated and the value is stored in the slot and returned.  This option
allows infrequently-used slots to take storage only when necessary.

{\bf :allocation :none} No storage is to be allocated; the slot should
not exist in instances of this class.  This is used to override
inheritance of slots defined by a super-class.

{\bf :default-value} {\it form\/} This is an alternate way for providing
a default initial value form.  The {\it form\/} is evaluated every time
it is used.  

{\bf :initable} {\it symbol\/} This specifies a non-nil symbol to be used to
specify an initial value of this slot, when a new instance is being
made.   {\it symbol\/} can be supplied as an {\bf \&key} argument to {\bf
make-instance}.   (This is still under discussion.)

{\bf :reader} {\it non-null-symbol\/} This specifies that a method for a
reader function should automatically be generated for this slot.  The
reader is a generic function named {\it non-null-symbol\/}.  A reader is
used to read the value of the slot.   This option does not cause a {\bf
setf} function to be defined.  {\it generic-function-name\/} must be a
non-null symbol.

Each {\it class-option\/} is an option that refers to the class.
The set of defined options is:

(:accessor-prefix string-or-symbol) This causes a method for an accessor
generic function to be generated automatically for each slot.  
The accessor is used to read the value of a slot and can be
used with {\bf setf} to write the value of a slot.  The name of each 
accessor is the prefix {\it string-or-symbol\/} followed by the name of
the slot, interned in the package current at the time {\bf defclass} is
macro-expanded. 

(:constructor symbol [boa-arglist]) This causes a constructor function
named {\it symbol\/} to be generated automatically.  The constructor is
used to make a new instance of the class.  If no {\it boa-arglist\/} is
present, the constructor takes keyword arguments.  If {\it
boa-arglist\/} is present, it describes the arguments to the
constructor.  The syntax of the {\bf :constructor\/} option to {\bf
defclass} is the same as that of the {\bf defstruct :constructor} option
described in ``Common Lisp the Language.''

(:default-init-plist {keyword argument}*) This option is still under
discussion; it is not yet clear whether it will be in the standard.  The
purpose of this option is to:  Set up defaults that are used when making 
an instance.   For example, a class might specify a default value to 
use to initialize a slot inherited from one of its super-classes. 
Each {\it keyword\/} must be a valid keyword argument to
{\bf make-instance}.  Each {\it argument\/} is a form that provides the default
value for that keyword argument if it is not supplied.  The user can
override the defaults in the {\bf :default-init-plist} by providing
keyword arguments to {\bf make-instance}.  The {\it arguments\/} are evaluated
every time they are used.

(:documentation string) This enables you to specify an arbitrary string
as documentation for this class.  The form (documentation class-name
'type) retrieves this string.

(:init-keywords {keyword}*) This option is still under discussion; it is
not yet clear whether it should be in the standard.  The purpose of this
option is to:  Specify that each given keyword is an allowed keyword
argument to {\bf make-instance} for this class.  There is no need to
provide this argument to make it possible to initialize slots; that is
done with the {\bf :initable-slots} option.  The {\bf :init-keywords}
option is used in conjunction with methods you have written for {\bf
make-instance}.  If a {\bf make-instance} method accepts an argument,
you must explicitly make it an allowed keyword argument to {\bf
make-instance} by using this option.

:initable-slots This specifies that it is allowed to initialize all
slots of this class.  The initialization can be done by providing the
keyword with the same name as the slot, followed by the slot's initial
value as an argument to {\bf make-instance}, or by including the keyword
and value in the {\bf :default-init-plist}.

(:instantiable t-or-nil) This option has not been discussed.
This specifies whether it is possible to directly
instantiate this class with {\bf make-instance}.  If {\bf :instantiable} is
{\bf nil}, the class cannot be instantiated and is termed an {\bf abstract 
class}.  The default value of {\bf :instantiable} is {\bf t}.

(:metaclass class-name) This specifies that this class has a different
implementation than the system-provided default.  If you have invented a
new metaclass, this option is the mechanism for creating classes of that
metaclass.  {\it class-name} is the name of a class that is capable of
being the class of a class.

(:predicate symbol)  This option has not been discussed yet.  This
generates a predicate function named {\it symbol\/}, which must be a
non-nil symbol.   The predicate function takes one argument, an object,
and returns {\bf t} if the object is of this class, {\bf nil} otherwise.  

(:reader-prefix string-or-symbol) This causes a method for a reader
generic function to be generated automatically for each slot.  The
reader is used to read the value of a slot.  This option does not cause
a {\bf setf} function to be defined.  The name of each reader is the
prefix {\it string-or-symbol\/} followed by the name of the slot,
interned in the package current at the time {\bf defclass} is
macro-expanded. 

\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

(defclass ship ()
               (name
                (x-velocity :accessor ship-x-vel)
                (y-velocity :accessor ship-y-vel)
                (mass :reader ship-mass))
  :initable-slots)

\endscreen!

\label Remarks:

Each class has a `component classes tree' composed of all its
super-classes, and the super-classes of each of its super-classes, and so
on.  This tree is used to compute the class precedence list of the class.
See the section ``Determining the Class Precedence List.''

Note the following rules of {\bf defclass}:

   - It is not required that the component classes of a class be
     defined before this {\bf defclass} is evaluated.

   - All the component classes of a class must be defined before it is
     permitted to make an instance of the class.

   - A class must be defined before it can be mentioned as an argument
     specifier in a {\bf defmethod}.

   - All component classes of a class must be defined before it is
     permitted to evaluate or compile a {\bf with-slots} that uses this
     class.

Slot-options and class-options are inherited by a class from its
components.   However, a class can override an option that would be
inherited from a component class simply by providing that option in the
{\bf defclass} form.

Some implementations might add other options to {\bf defclass}.  Therefore it is
required that all implementations signal an error if they observe a
class-option or a slot-option that is not implemented locally.

If no default value for a slot is specified either in the {\bf defclass} or the
{\bf make-instance} form, the initial value of the slot is undefined and it is an
error to reference it.  This is the same behavior as a {\bf defvar} with no
initial value form.

When the definition of a class changes, each existing instance of the class
is updated to the new format the next time it is accessed.  (Note that this
behavior might be categorized as an optional feature.)

It is valid to specify more than one accessor, reader, and keyword for
initialization, for a single slot.  For example, this can happen when
the {\bf :accessor} slot option is used to specify an accessor for a 
slot, and the {\bf :accessor-prefix} option is used to specify that all 
slots should have an accessor with the supplied prefix. 

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or {\bf
with-slots} using {\bf :use-accessors nil}.

The following slot-options may appear more than once:

    {bf :accessor}
    {bf :reader}
    {bf :initable}

The following class-options may appear more than once:

    {bf :accessor-prefix}
    {bf :constructor}
    {bf :default-init-plist}
    {bf :init-keywords}
    {bf :predicate}
    {bf :reader-prefix}

No other slot-option or class-option may appear more than once in a
single {bf defclass} form.

\label See Also:

{\bf with-slots}

{\bf slot-value}

See the section ``Determining the Class Precedence List.''

\endcom



\begincom{defgeneric}

\label Purpose:

The macro {\bf defgeneric} defines a generic function and stores it in
the symbol function cell of the symbol that is its name.  The new
generic function object is returned as the result.  {\bf defgeneric} 
allows you to specify options and declarations that pertain to the 
generic function as a whole. 

It is still under discussion whether it should be required that a {\bf
defgeneric} must be evaluated before any methods are defined, or whether
{\bf defmethod} should set up a generic function with default options,
if no {\bf defgeneric} has been evaluated.

\label Syntax:

(defgeneric generic-function-name lambda-list {option}*)

option ::= (:argument-precedence-order {parameter-name}+)
           (declare {declaration}+)
           (:documentation string) | string
           (:generic-function-class class-name)
           (:interface {form}+)
           (:method-arguments {lambda-list}+)
           (:method-class class-name) 
           (:method-combination name {argument}*)


\Defmac {defgeneric} {name lambda-list \ttbrac{documentation} \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-order-list\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{$\ldots$}}}

\label Arguments:

{\it generic-function-name} is a non-null symbol naming the generic function.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

1.  No \&aux variables are allowed. 
2.  Optionals (including keyword arguments) may not have default-forms
    or use supplied-p.  Thus the symbol does not imply a default value 
    of NIL.   Note that optionals in the methods can have default forms
    and supplied-p. 

The set of defined options is:

(:argument-precedence-order {parameter-name}+)
                This option alters the default way of selecting methods.
                By default, all required arguments are considered
                from left to right; each required argument has
                precedence over those to its right.  When this option is
                used, each required argument should be included as a
                parameter-name, so the full precedence order is supplied.

(declare {declaration}+)
                Declarations that apply to the whole function (as opposed
                to declarations of variables) are permitted.   Type
                declarations of the parameters are allowed; some Common 
		Lisp implementations use this when compiling calls to
    		the generic function. The only 
                declaration in this standard is optimize, which can have
                the value of speed or space.  This allows the user to
                control whether method selection is optimized for speed or
                space; it has no effect on individual methods.  Some
                implementations might support other declarations.  If an
                implementation notices a declaration that it does not
                support, it should follow the rules described on page 161
                of Common Lisp the Language.

(:documentation string) | string
                Associates a documentation string with the generic
                function.  The form (documentation generic-function-name
                'function) retrieves this string.

(:generic-function-class class-name)
                Specifies that this generic function has a different
                implementation than the system-provided default.  If you
                have invented a new generic function class, this option is
                the mechanism for creating a generic function of the new
                class.  class-name is the name of a class that is capable
                of being the class of a generic function.

(:interface {form}+)
		This option is under discussion.
                Defines a function that runs instead of the generic
                dispatch.  This is completely transparent to anyone calling
                the generic function.  Such a prologue function can be used
                to rearrange the arguments, to standardize the arguments
                before the methods see them, to default optional arguments,
                to do the shared non-generic portion of an operation, or
                for any other purpose.

                Inside the forms you can trigger the generic dispatch with
                (call-next-method args...) or (apply-next-method args...).
		apply-next-method treats the last argument as a list of
                arguments just like apply.  

(:method-arguments {lambda-list}+)
		This option is under discussion. 
                You can use this option to specify that the methods accept
                different arguments than does the generic function itself.
                By default, the methods receive the same arguments that are
                specified at the top of the defgeneric form.   If
		:interface is also specified, it provides the
		translation from generic-function arguments to 
		method-arguments.   If :interface is not specified, the
		arguments are permuted according to matching names, and
		all names in the :method-arguments lambda-list must also
		appear in the generic-function's lambda-list.   For
                example:
			
		(defgeneric foo (x y \&optional z) 
                   (:method-arguments y x z)) 

(:method-class class-name)
                This is used to specify that all methods for this generic
                function have a different implementation than the
                system-provided default.  If you have invented a new method
                class, this option is the mechanism for creating methods of
                the new class.  Once the defgeneric form with this option
                is evaluated or compiled, any methods you define with
                defmethod will be implemented in the class name specified
                here.  class-name is the name of a class that is capable of
                being the class of a method.

(:method-combination name {argument}*)
                Indicates that the generic function uses the type of method
                combination named by name.  The arguments depend on the
                type of method combination.  The most common argument is
                one to specify the order of methods, which is either
                :most-specific-first or :most-specific-last.  The default
                method combination type is :daemon, with the
                :most-specific-first order.

\label Values:

The new generic function object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function and use of {\bf defgeneric} is closely related to the
design of the method combination mechanism and the specification of
discrimination on optional arguments.  The name of {\bf defgeneric} is
subject to change, depending on the results of these decisions.

If a {\bf defgeneric} form is evaluated when a generic function of the
same name is already defined, the new definition replaces the old.

If a {\bf defgeneric} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf defgeneric}, an error is signalled.  

Some implementations might add other options to {\bf defgeneric}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\endcom




\begincom{defgeneric-setf}

\label Purpose:

{\bf defgeneric-setf} enables you to define a {\bf setf} generic
function.  A {\bf setf} generic function is called in an expression such as: 

({bf setf} ({\it generic-function-name arguments...\/}) {\it new-value\/}) 

The new generic function object is returned as the result. 

\label Syntax:

(defgeneric-setf generic-function-name lambda-list setf-lambda-list {option}*)

option ::= (:documentation string) | string
           (:method-combination name {argument}*)
           (declare {declaration}+)
           (:argument-precedence-order {parameter-name}+)
           (:interface {form}+)
           (:method-arguments {lambda-list}+)
           (:generic-function-class class-name)
           (:method-class class-name) 

\label Arguments:

{\it generic-function-name} is a non-null symbol naming a generic
function.   

The {\it lambda-list\/} argument is the same as for {\bf defgeneric}.

{\it setf-lambda-list} is ({\it variable-name\/}).  {\it
variable-name\/} is the name of the variable that gets bound to the
value {\it foo\/} in ({\bf setf} ({\it name x y z\/}) {\it foo\/}).
Like the variable names in the {\it lambda-list\/} it is only for
documentation. 

The keyword options are the same as for {\bf defgeneric}. 
 
\label Values:

The new generic function object is returned as the result.

\label Examples:

\label Remarks:

\label See Also:

{\bf defgeneric}
{\bf defmethod}

\endcom




\begincom{define-method-combination}

\label Purpose:

{\bf define-method-combination} is a mechanism for declaring a new type
of method combination.

At present the details of this function and related functions are under
discussion.    

\label Syntax:

\label Arguments:

\label Values:

\label Examples:

\label Remarks:

\endcom



\begincom{defmethod}

\label Purpose:

The macro {\bf defmethod} defines a new method for performing a generic
function.  It returns the new method as its result.

The argument list of the method must be congruent with the argument 
list of the generic function.  If this condition does not hold, an error is
signalled.  See "Generic Functions and Methods" for 
a definition of congruency in this context.  

[The following is under discussion:  A generic function of the given name
must exist before any methods of that name can be defined.]

\label Syntax:

   (defmethod generic-function-name {qualifier}*
              specialized-lambda-list 
     {declaration | doc-string}*
     {form}*)

\Defmac {defmethod} {generic-function-name
\vtop{\hbox{\star{\curly{qualifier}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it generic-function-name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

generic-function-name
                A non-null symbol that names the generic function
                being specialized.   

qualifier       A object used by method combination to identify the
                method.  For example, :before, :after, or :around. 
		qualifier cannot be a list (or NIL, the empty list). 

specialized-lambda-list
                A lambda-list as defined in Common Lisp the Language, page
                60, possibly with some required arguments replaced by
                specialized parameters so that method selection uses that 
                argument.  A specialized parameter is a list such as:
                (variable-name parameter-specializer).  Only required
                parameters may be specialized.  [Note that the
                specialization on optional parameters is still under
                discussion.]  
 
parameter-specializer  
 		parameter-specializer can be symbol that names a
                user-defined class, or a structure defined by defstruct
                if the :type option was not used, or a class
                corresponding to a Common Lisp type specifier.   Note
                that not all Common Lisp types have a corresponding
                class.   The section "Generic Functions and Methods"
                lists the Common Lisp types that have corresponding
                classes. 

                parameter-specializer can also be (QUOTE object) to
		indicate that this argument must be EQL to the quoted
                object for this method to be applicable.  

                Note that the use of t as a parameter-specializer defines a
                default method.  Such a method is selected only when no
                more specific method for the generic function is defined.

\label Values:

The new method object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

\label See Also:

See the section "Generic Functions and Methods". 

\endcom


\begincom{defmethod-setf}

\label Purpose:

The macro {\bf defmethod-setf} defines a method for a {\bf setf} generic
function.  A {\bf setf} generic function is called in an expression such as: 

({bf setf} ({\it generic-function-name arguments...\/}) {\it new-value\/}) 

\label Syntax:

   (defmethod-setf generic-function-name {qualifier}*
                   specialized-lambda-list
                   setf-lambda-list
     {declaration | doc-string}*
     {form}*)

\Defmac {defmethod-setf} {generic-function-name
\vtop{\hbox{\star{\curly{qualifier}}}
\hbox{specialized-lambda-list specialized-setf-vars}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it generic-function-name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-vars\/}::$=$ (\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The arguments {\it generic-function-name\/}, {\it qualifier\/}, and
{\it specialized-lambda-list\/} are the same as for {\bf defmethod}.

{\it setf-lambda-list\/} is the same as {\it specialized-lambda-list\/}
except that for now there can be only one parameter.  In other words,
{\it setf-lambda-list\/} is a lambda list containing exactly one
required parameter, which may be specialized.  It is either ({\it
variable-name\/}) or (({\it variable-name parameter-specializer\/})).

\label Values:

The new method object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}

\label Purpose:

The existing describe function is required to be replaced by this generic
function.

(defgeneric describe (object))

Each implementation is required to replace its former implementation of
describe with one or more methods.  Exactly which classes have methods for
describe is not specified.

Users can also write methods for describe; these methods must conform to
the Common Lisp definition of describe in Common Lisp the Language.  A
user-defined class without a method for describe inherits an appropriate
system-defined method.

\label Syntax:

\Defun {describe} {object}

\label Arguments:

{\it object\/} is any Lisp object. 

\label Values:

As described in {\it Common Lisp the Language\/}.

\label Examples:

\endcom



\begincom{documentation}


\label Purpose:

The Common Lisp function {\bf documentation} is extended as follows:
If the symbol names a generic function, {\bf documentation} returns the
documentation string for the generic function.
If the first argument is a method, the documentation string of the method
is returned.
If the first argument is a class object, the documentation string for the
class is returned.

\label Syntax:

\Defun documentation {symbol doc-type}

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function, method, or class.

\endcom



\begincom{function-parameters}

\label Purpose:

The function {\bf function-parameters} returns the lambda list of its
argument from which default values for {\bf \&optional} and {\bf \&key}
parameters and supplied-p parameters have been removed.

\label Syntax:

\Defun {function-parameters} {function-or-generic-function}

\label Arguments:

The argument to {\bf function-parameters} is a function, generic function, or
a symbol that names a function or generic function.

\label Values:

The result of {\bf function-parameters} is a copy of the lambda list of its
argument from which default values for {\bf \&optional} and {\bf \&key}
parameters and supplied-p parameters have been removed.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[It is intended that this function correspond to whatever
{\bf function-parameters} is adopted for Common Lisp.]

The macro {\bf setf} can be used with {\bf function-parameters}.


\endcom


\begincom{generic-function-method-combination}

\label Purpose:

The function {\bf generic-function-method-combination} returns the method combination
for the given generic function.

\label Syntax:

\Defun {generic-function-method-combination} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic
function or a symbol that names a generic function.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{generic-function-p}

\label Purpose:

The predicate {\bf generic-function-p} is true if its argument is a
generic function, otherwise it is false.

\label Syntax:

\Defun {generic-function-p} {object}

\label Values:

A non-{\bf nil} value is returned if the argument is a generic function
object, otherwise the result is {\bf nil}.

\label Examples:

\screen!
\endscreen!

\endcom



\begincom{get-method}

\label Purpose:

The function {\bf get-method} takes a generic function and returns the
method object that has the given argument qualifiers and specializers.
If no such method exists, {\bf get-method} returns {\bf nil}.

\label Syntax:

\Defun {get-method} {generic-function qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.  An error is signalled if no
such function exists.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument specializers
for the method.  If {\it specializers\/} is {\bf nil}, the
default method function for that generic function is returned.

\label Values:

The result of {\bf get-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf get-method} returns {\bf nil}.

\label Examples:

\screen!

\endscreen!

\endcom



\begincom{lambda-list-specializers}

\label Purpose:

The function {\bf lambda-list-specializers} takes a {\bf
defmethod} lambda list and returns a list containing the argument
specializers for all required arguments.  The specializer {\bf t} is
returned for any lambda list argument for which no argument specializer
was given.

\label Syntax:

\Defun {lambda-list-specializers} {specialized-lambda-list}

\label Values:

The result of {\bf lambda-list-specializers} is a list of the argument
specifiers for all required arguments in the given lambda list.

\endcom


\begincom{make-generic-function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :function-parameters :argument-precedence-order}
\hbox{ :method-combination-type :documentation \dots}}}

\label Arguments:

The {\bf :function-parameters} argument is a lambda list.

The {\bf :argument-precedence-order} argument is a list that is a
permutation of all the required parameters of the generic function lambda list.

The {\bf :method-combination-type} argument is a symbol.

The {\bf :documentation} argument is a string.

\label Values:

The result of {\bf make-generic-function} is a generic function object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function {\bf make-generic-function} is intended to be the
programmatic interface to {\bf defgeneric}.

\label See Also:

{\bf defgeneric}

\endcom

\begincom{make-instance}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class or a symbol that names a class.

\label Values:

The new instance is returned.

\label Remarks:

[Discussion of initialization to go here.]

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

It is not possible to make an instance of class created with {\bf defclass}
if the {\bf :instantiable} option was {\bf nil}.  An error is signalled in
this case.

\label See Also:

{\bf class-of}

\endcom


\begincom{print-object}

\label Purpose:

PRINT-OBJECT outputs the printed representation of the object onto the
stream.  PRINT-OBJECT is called by the print system, and should not be
called by the user.  A user-defined class can have a method for
PRINT-OBJECT that defines its printed representation.  If it has no method,
it inherits a system-defined method which produces a default 
printed-representation, perhaps using a syntax such as \#<...> that is not
understood by the reader.

\label Syntax:

(defgeneric print-object (object stream))

\label Arguments:

\label Values:

\label Examples:

\label Remarks:

Each PRINT-OBJECT method must obey the print-control special variables
as documented in Common Lisp the Language pp. 370-373.  The specific
details are:

*PRINT-ESCAPE*  Each method must implement this.

*PRINT-PRETTY*  This can be ignored by most methods other than the one for
                lists.

*PRINT-CIRCLE*  This is handled by the printer and can be ignored by
                methods.

*PRINT-LEVEL*   The printer takes care of this automatically, provided that
                each method handles exactly one level of structure and
                calls write (or an equivalent function) recursively if
                there are more structural levels.  The printer's decision
                of whether an object has components, and therefore should
                not be printed when the printing depth is not less than
                *PRINT-LEVEL*, is implementation-dependent.  In some
                implementations its PRINT-OBJECT method is not called, in
                others the method is called and the determination that the
                object has components is based on what it tries to output
                to the stream.

*PRINT-LENGTH*  Methods that produce output of indefinite length must obey
                this, but most methods other than the one for lists can
                ignore it.

*PRINT-BASE*, *PRINT-RADIX*, *PRINT-CASE*, *PRINT-GENSYM*, and
*PRINT-ARRAY* apply to specific types of objects and are handled by the
methods for those objects.

In general, the printer and the PRINT-OBJECT methods should not rebind the
print-control variables as they recurse through the structure, but this is
necessarily implementation-dependent.

In some implementations the stream argument passed to a PRINT-OBJECT method
is not the original stream, but is an intermediate stream that implements
part of the printer, so methods should not depend on the identity of this
stream.

All of the existing printing functions (write, prin1, print, princ, pprint,
write-to-string, prin1-to-string, princ-to-string, the format ~S and ~A
operations, and the format ~B, ~D, ~E, ~F, ~G, ~\$, ~O, ~R, and ~X
operations when they encounter a non-numeric value) are required to be
changed to go through the PRINT-OBJECT generic function.  Each
implementation is required to replace its former implementation of printing
with one or more PRINT-OBJECT methods.  Exactly which classes have methods
for PRINT-OBJECT is not specified; it would be valid for an implementation
to have one default method that is inherited by all system-defined classes.

References: See MIT AI Memo 816, December 1984, by Richard C. Waters for a
discussion of PP, one of the better designed Lisp printers.  It handles
*PRINT-LEVEL* and *PRINT-LENGTH* invisibly to the PRINT-OBJECT methods.
See also the inconclusive discussion on printing, *PRINT-LEVEL*, and
recursion on the Common-Lisp mailing list around 21 November 1985 for
additional background.

\endcom



\begincom{remove-class}

\label Purpose:

\label Syntax:

\Defun {remove-class} {class}

\label Arguments:

\label Values:

\label Examples:

\endcom



\begincom{remove-method}

\label Purpose:

The function {\bf remove-method} removes the method for the given
name, qualifiers, and argument specializers from the corresponding
generic function.

The method {\bf remove-method} returns the method object if it succeeds and
{\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-method} {generic-function qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument
specializers for the arguments of the method that is to be removed.
If the {\it specializers\/} list contains fewer elements than the
lambda list of the corresponding generic function, the remaining
elements are considered to be {\bf t}.

\label Values:

The result of {\bf remove-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf remove-method} returns {\bf nil}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The {\it specializers\/} list can be obtained from a {\bf defmethod}
lambda list by use of the function {\bf lambda-list-specializers}.

\label See Also:

{\bf lambda-list-specializers

remove-setf-method

defmethod

get-method}

\endcom



\begincom{remove-setf-method}

\label Purpose:

The function {\bf remove-setf-method} removes the {\bf setf} method for
the given name, qualifiers, and argument specializers from the corresponding
generic function.

The method {\bf remove-setf-method} returns the given method object if it 
succeeds and {\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-setf-method} {generic-function qualifiers specializers setf-specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of
the argument specializers for the arguments of the
method that is to be removed.  If the {\it specializers\/}
list contains fewer elements than the lambda list of the corresponding
generic function, the remaining elements are considered to be {\bf t}.

The {\it specializers\/} list can be obtained from a
{\bf defmethod} lambda list by use of the function 
{\bf lambda-list-specializers}.

\label Values:

The result of {\bf remove-setf-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf remove-setf-method} returns {\bf nil}.

\label See Also:

{\bf lambda-list-specializers

remove-method

defmethod}

\endcom


\begincom{slot-value}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot unless the slot is read-only.

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for using slots as
variables.  Within such a context the slot can be specified by its slot
name, as if it were a lexically bound variable.   {\bf setf} and {\bf
setq} can be used to set the value of the slot. 

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
(unless ({\bf :use-accessors nil}) is specified.

\label Syntax:  

(with-slots ({instance | (instance {option}*)}* form*)


\Defmac {with-slots} {\paren {\star{\curly{var-name $\vert$ varspec}}} \star{\form}}

{\it varspec\/}::$=$ {\paren {var-name {\star{\curly{options}}}}}

{\it options\/}::$=$  {\tt\vtop{\hbox{:use-accessors {\it t-or-nil\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The expression {\it instance\/} must evaluate to an instance; it is
evaluated exactly once.  

It is necessary that the class of the instance can be determined.
Either {\it instance\/} must be the name of a specialized parameter in
the lambda-list of a method lexically containing this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.

The recognized keywords and their arguments are:

:class class-name
                The class, or a super class, of the instance.  This option
                is necessary if the class of the instance cannot be
                determined from the lambda-list of a method lexically 
		containing this with-slots form.

:prefix prefix-string
                When you use this option you can
                reference a slot by the variable named by prefix followed
                by the slot name.  This enables you to keep separate two
                instances whose slot names overlap, such as when you want
                to access two instances of the same class, or that share a
                super-class.

:use-accessors t-or-nil
		If t, when a slot is accessed, the accessor function
		generated by defclass is used to access the slots; this
		means that any methods written for the accessor are also
		run.   t is the default.   If nil, with-slots accesses 
		the slots using slot-value instead of the accessor.
		If the {\bf defclass} form did not specifically generate 
                accessors, the ({\bf :use-accessors nil} option should be used. 

\label Values:

The value of the {\bf with-slots} form itself is whatever is returned by
the last form in its body. 

\label Examples:

\screen!

(defclass point () ((x 0) (y 0))
  (:accessor-prefix point-))

(defmethod move ((p point) dx dy)
  (with-slots (p)  ;; p is known as a point from the method args
    (setf x (+ x dx) y (+ y dy))))

(defmethod move ((p point) dx dy)
  (with-slots ((p :use-accessors nil))
    (setf x (+ x dx) y (+ y dy))))

(defmethod make-same-height ((p1 point) (p2 point))
  (with-slots ((p1 :prefix p1-) (p2 :prefix p2-))
    (setf p1-y p2-y)))

(defmethod make-horizontal ((l line))
   (let ((left (left-point l)) (right (right-point l)))
     (with-slots ((left  :class point :prefix left-)
                  (right :class point :prefix right-))
       (setf left-y right-y))))

\endscreen!

\label Remarks:

The examples above use {\bf setf} with the variables inside {\bf
with-slots} forms; it is also allowed to use {\bf setq}.  

It is an error if the class of {\it instance} cannot be inferred from
the lexical context in which it occurs.  If any ambiguity is detected,
{\bf with-slots} signals an error.

\endcom
\endChapter
\bye